home *** CD-ROM | disk | FTP | other *** search
/ PD Collection CD 1 / PD Collection CD 1.iso / sound / protrack / docs / module doc < prev    next >
Text File  |  1995-01-17  |  16KB  |  377 lines
  1.  
  2.                       TrackerModule 5.12 (Sep 1994)
  3.                       --------------------------------
  4.  
  5. This is the latest version of the Arc SoundTracker player written by
  6. Composite Reality of Archimedes Freelancers. It plays exclusively new-format
  7. modules, created using ArcProTracker, TechTracker or Tracker.
  8.  
  9. This module can be found on the 'ST-00" disc as 'bin.prop'.
  10.  
  11. CLI Commands offered
  12. --------------------
  13. The module implements the standard range of TrackerModule CLI commands
  14.  
  15. -----------------------------------------------------------------------------
  16. *PlayMod <filename> - load and start to play SoundTracker module
  17. -----------------------------------------------------------------------------
  18.  
  19. This command allocates space in RMA, loads the specified file and sets the
  20. player into play mode. Any previously playing tune is stopped as soon as the
  21. command is issued.
  22.  
  23. -----------------------------------------------------------------------------
  24. *PlayStart          - set player to play mode
  25. -----------------------------------------------------------------------------
  26.  
  27. This command will start a tune playing that has previously been paused using
  28. SWI Tracker_Pause or *PlayPause. The tune will continue from exactly where
  29. it left off.
  30.  
  31. -----------------------------------------------------------------------------
  32. *PlayPause          - set player to pause mode
  33. -----------------------------------------------------------------------------
  34.  
  35. This command will pause the currently playing SoundTracker module.
  36.  
  37. -----------------------------------------------------------------------------
  38. *PlayStop           - set player to stop mode
  39. -----------------------------------------------------------------------------
  40.  
  41. This command will stop the currently playing tune and release all memory and
  42. verctors allocated to it. This command terminates a tune completely, and it
  43. cannot be restarted.
  44.  
  45. -----------------------------------------------------------------------------
  46. *SetPlayPos         - set position in sequence list
  47. -----------------------------------------------------------------------------
  48.  
  49. This command will force the player to play the tune from the top of the
  50. pattern at the specified position in the sequence list.
  51.  
  52. -----------------------------------------------------------------------------
  53. *PlayStatus         - return useful textual information
  54. -----------------------------------------------------------------------------
  55.  
  56. This command displays the tune name, author name, length (in positions and
  57. bytes), number of voices and the names of all samples in the tune.
  58.  
  59. SWI COMMANDS
  60. ------------
  61. After seeing Matt Farrow's TrackerModule 4.00 SWI calls, I thought it would
  62. be a good idea if I included the same calls in TrackerModule 5.10 for
  63. compatability and also because they're genuinely useful!
  64.  
  65. There are a few alterations to some data passed/returned to cater for the
  66. differeces in 4.00 and 5.12. However these differences just mean simpler
  67. results from the calls as this version isn't attempting to play old format
  68. tunes (as there's no point really - just convert it to the equivalent new
  69. format)
  70.  
  71. Note: The SWI chunk base number is an officially recognised chunk base
  72.       number supplied by Acorn!
  73.  
  74. -----------------------------------------------------------------------------
  75. Tracker_Version        (SWI &43200)
  76. -----------------------------------------------------------------------------
  77.  
  78. No entry parameters
  79.  
  80. On exit :  R0 = version number × 100  (ie. for version 5.12 = 512)
  81.  
  82. This call allows the TrackerModule version number to be ascertained.
  83. (Note: Only versions 4.00 upwards support this feature)
  84.  
  85. -----------------------------------------------------------------------------
  86. Tracker_Load           (SWI &43201)
  87. -----------------------------------------------------------------------------
  88.  
  89. On entry:  R0 = pointer to filename of SoundTracker module
  90.  
  91. On exit :  R0 preserved
  92.  
  93. This call will load the specified SoundTracker module ready for playing.
  94. (Note: this call will set the player to pause mode. The Tracker_Play routine
  95.        must be called, or a *PlayStart issued in order to start playing)
  96.  
  97. -----------------------------------------------------------------------------
  98. Tracker_MemoryLoad     (SWI &43202)
  99. -----------------------------------------------------------------------------
  100.  
  101. On entry:  R0 = pointer to start of SoundTracker module in memory
  102.  
  103. On exit :  R0,R1 preserved
  104.  
  105. This call will setup the player to play the specified SoundTracker module at
  106. the memory location specified. This call is equivalent to Tracker_Load
  107. except that the tune is assumed to be already in memory.
  108. In this version, R1 need not be set to the tune length (in bytes) as this is
  109. automatically derived from the new format file.
  110.  
  111. (Note: this call will set the player to pause mode. The Tracker_Play routine
  112.        must be called, or a *PlayStart issued in order to start playing)
  113.  
  114. -----------------------------------------------------------------------------
  115. Tracker_Play           (SWI &43203)
  116. -----------------------------------------------------------------------------
  117.  
  118. No entry parameters
  119.  
  120. No exit parameters
  121.  
  122. This call will restart a tune after it has been paused.
  123. Exactly eqivalent to *PlayStart
  124.  
  125. -----------------------------------------------------------------------------
  126. Tracker_Stop           (SWI &43204)
  127. -----------------------------------------------------------------------------
  128.  
  129. No entry parameters
  130.  
  131. No exit parameters
  132.  
  133. This call will stop a tune, and release all memory/vectors. Exactly
  134. equivalent to *PlayStop
  135.  
  136. -----------------------------------------------------------------------------
  137. Tracker_Pause          (SWI &43205)
  138. -----------------------------------------------------------------------------
  139.  
  140. No entry parameters
  141.  
  142. No exit parameters
  143.  
  144. This call will pause a tune. Exactly equivalent to *PlayPause
  145.  
  146. -----------------------------------------------------------------------------
  147. Tracker_Stereo         (SWI &43206)
  148. -----------------------------------------------------------------------------
  149.  
  150. On Entry:  R0 = Stereo setting (0-4)
  151.  
  152. On Exit :  R0 preserved
  153.  
  154. This performs the same actions as *PlayStereo, with R0 passed as a parameter.
  155. If R0 is set to 4 on entry, then the stereo settings will be unaltered
  156. whenever a module is loaded or killed, and disables any stereo commands in
  157. tracker modules. This is to allow interfacing programs to provide their own
  158. stereo options, or to allow adjustment to the stereo positions while tracker
  159. tunes are playing (which have default stereo settings stored as part of the
  160. tune).
  161.  
  162. -----------------------------------------------------------------------------
  163. Tracker_SetPos         (SWI &43207)
  164. -----------------------------------------------------------------------------
  165.  
  166. On Entry:  R0 = New sequence position (0-127 max)
  167.            R1 = Event (0-63 max)
  168.  
  169. On Exit :  R0,R1 preserved
  170.  
  171. This performs the same actions as *SetPlayPos, except that the event within
  172. the pattern to start playing at can be specified. If an event number higher
  173. than the number of events in the current pattern is specified, the pattern
  174. will begin at event 0.
  175.  
  176. If there is no tune currently loaded, an error is generated.
  177.  
  178. -----------------------------------------------------------------------------
  179. Tracker_ReadPos        (SWI &43208)
  180. -----------------------------------------------------------------------------
  181.  
  182. No entry parameters
  183.  
  184. On Exit :  R0 = Current position in sequence table (0-127 max)
  185.            R1 = Current position in pattern (0-63 max)
  186.            R2 = Maximum position in sequence table (music length)
  187.  
  188. This call returns the current position, event in the current pattern, and
  189. the total music length.
  190.  
  191. -----------------------------------------------------------------------------
  192. Tracker_PlayNote       (SWI &43209)
  193. -----------------------------------------------------------------------------
  194.  
  195. On Entry:  R0 = Sound channel to sound note on (1-8)
  196.            R1 = Note number (1-36) or period (100-1000)
  197.            R2 = Sample to play (1-47 max)
  198.            R3 = Volume (0-255) or -1 (use sample's default volume)
  199.  
  200. On Exit :  R0-R3 preserved
  201.  
  202. If tune not paused then C flag set otherwise C flag cleared.
  203. If there is no tune loaded, an error will be generated.
  204.  
  205. This call will play a sample at a given pitch and volume on a specified
  206. channel. Make sure first that the channel you intend to play the note on is
  207. attached to 'TrackerVox'. For instance if you are playing a 6 track tune,
  208. 8 tracks will be available (as always) but 7 and 8 will not be attached to
  209. anything. The first 6 channels as used by the tune can be used by this call
  210. as they are automatically attached to TrackerVox. Of course 7 and 8 are
  211. available and nothing is being played on them, so therefore these two
  212. channels can be used for sound effects. Attach them to TrackerVox using SWI
  213. Sound_AttachNamedVoice and then call SWI Tracker_PlayNote.
  214. Note that sample numbers outside the range offered by the module cannot be
  215. used. A module can contain any number of samples between 0 and 47.
  216.  
  217. -----------------------------------------------------------------------------
  218. Tracker_TuneInfo       (SWI &4320A)
  219. -----------------------------------------------------------------------------
  220.  
  221. No entry parameters
  222.  
  223. On Exit :  R0 = Sequence table length/music length (1-128)
  224.            R1 = Number of voices (1-8)
  225.            R2 = Current speed (1-31) or tempo (32-255)
  226.            R3 = Pointer to tune name (0 terminated, max length 32 chars)
  227.            R4 = Pointer to author's name (0 terminated, max length 32 chars)
  228.            R5 = Address of currently loaded tune module
  229.  
  230. If the tune is paused, the C flag is set, otherwise the C flag is cleared.
  231. If there is no tune loaded, R0 is set to zero, and R1-R5 are preserved.
  232.  
  233. This call provides miscellaneous information about the tune currently loaded.
  234.  
  235. You should not need to directly access the tune module (using the address
  236. passed in R5), because all information is available via the various SWI's.
  237. This information is provided if, for example, multi-tasking players/editors
  238. need to know if the tune currently playing is running from ordinary RMA, or
  239. the player's/editor's own workspace.
  240.  
  241. -----------------------------------------------------------------------------
  242. Tracker_SoundInfo      (SWI &4320B)
  243. -----------------------------------------------------------------------------
  244.  
  245. On Entry:  R0 = Pointer to word-aligned 256 byte block to hold sound data
  246.  
  247. On Exit :  R0 preserved
  248.               
  249. If the tune is paused, the C flag will be set, otherwise the C flag will be
  250. cleared.
  251.  
  252. If there is no tune loaded an error will be generated.
  253.  
  254. This call is only provided for advanced uses of TrackerModule, and involves
  255. information of a highly technical nature. It is advised that you do not use
  256. this call if you can avoid it.
  257.  
  258. The call will transfer the current contents of the sound voice info table
  259. to the location pointed to by R0. 256 bytes (64 words) will be transferred
  260. in total (8 words per sound channel), regardless of the number of voices
  261. actually active.
  262.  
  263. When a note is played and then ends, word 6 of the appropriate channel is
  264. zeroed. The sound routines will only try and play the sample if this word is
  265. non-zero.
  266.  
  267. When a tune is paused, the block is saved and overwritten with zeros. When
  268. the tune is restarted, the old contents are restored, so that the samples
  269. will continue to play from the same point.
  270.  
  271.  The format of the table is as follows:-
  272.  
  273. Word  Offset       Sound channel 1...
  274. 0     +0      The current pitch accumulator. (shift right 16 bits to get the
  275.               actual byte offset into the sample being played).
  276.  
  277. 1     +4      The current pitch increment (added to accumulator after every
  278.               byte filled). This is obtained using internal tables given the
  279.               sample period (word 7)
  280.  
  281. 2     +8      The sample loop offset (given in bytes). When the routine
  282.               reaches the end of a sample or the sample length, the accumul-
  283.               ator is loaded with this value shifted left 16 bits (ie. to
  284.               give a byte offset). If this is a zero value, the sample will
  285.               stop instead of looping.
  286.  
  287. 3     +12     The sample length / repeat length (in bytes). The routine
  288.               checks every 4 bytes filled to see if the current accumulator
  289.               exceeds this value when shifted right 16 bits. (See above)
  290.  
  291. 4     +16     The sample number (1-36).
  292.  
  293. 5     +20     The current volume (0-255). This value is subtracted from every
  294.               byte filled, therefore 0 = maximum volume and 255 = silent.
  295.               NB This is the reverse of the normal volume command.
  296.  
  297. 6     +24     This is the tracker format note number of the sample being
  298.               played (1-36, 1=C octave 1 36=B octave 3). The arpeggio command
  299.               makes use of this word. If this word is zero, no sound will be
  300.               played.
  301.  
  302. 7     +28     This is a copy of the sample period (from which the pitch
  303.               increment value is calculated), and is used by the portamento
  304.               commands. The range of the sample period is from 1 to hex &400
  305.               (although the portamento commands have smaller limits in
  306.               practice).
  307.  
  308. 8     +32     Word 0 of sound channel 2...
  309.  
  310. 9     +36     Word 1 of sound channel 2...  etc. 
  311.      
  312.     -> word 8 of sound channel 8
  313.  
  314. -----------------------------------------------------------------------------
  315. Tracker_ReadSampleTable   (SWI &4320C)
  316. -----------------------------------------------------------------------------
  317.  
  318. On Entry:  R0 = Sample number (1-47)
  319.  
  320. On Exit :  R0 preserved
  321.            R1 = Pointer to sample name (0-terminated, max length 24 chars)
  322.            R2 = Sample length (bytes)
  323.            R3 = LSB - Sample volume (0-255) MSB - Finetune (0-15)
  324.            R4 = Repeat offset (bytes)
  325.            R5 = Repeat length (bytes)
  326.            R6 = Address of raw sample data
  327.  
  328. This call returns all relevant information about the specified sample. 
  329. If there is no tune loaded, an error will be generated.
  330.  
  331. =============================================================================
  332.                                
  333. Errors
  334. ------                                                    
  335.  
  336. The error numbers and messages which TrackerModule may generate:
  337.  
  338. No tune loaded                 - An operation was attempted which requires a
  339. (&43200)                         tune to be loaded into memory beforehand
  340.                                  using *PlayMod or SWI Tracker_Load.
  341.  
  342. Sequence position out of range - The sequence position given with *SetPlayPos(&43201)                         or SWI Tracker_SetPos was higher than the
  343.                                  tune's music length.
  344.  
  345. No room for module             - TrackerModule could not claim enough
  346. (&43202)                         RMA workspace to load the module. To get
  347.                                  more memory quit an application and
  348.                                  retry.
  349.  
  350. Channel number out of range    - The sound channel number was not a value
  351. (&43203)                         between 1 and the number of sound channels
  352.                                  used for that particular tune.
  353.  
  354. Note number out of range       - The note number was not within the range of
  355. (&43205)                         1-36.
  356.  
  357. Sample number out of range     - The sample number was not within the range
  358. (&43204)                         of 0 to the number of samples used for that 
  359.                                  particular tune.
  360.  
  361. Volume out of range            - The volume was not within the range of
  362. (&43206)                         0-255, or -1.
  363.  
  364. =============================================================================
  365.  
  366. New features over previous new format players
  367. ---------------------------------------------
  368. New format modules to be played by  5.12 can include:
  369.  
  370. * Finetune values
  371. * Restart position (as on NoiseTracker)
  372. * Sample zero
  373. * Any number of samples from 0-47
  374. * Samples upto 1Mb long                              
  375. * Secondary tempo commands
  376.  
  377. -----------------------------------------------------------------------------